The Datafile PD-CD 1 Issue 2/PDCD-1 - Issue 02.iso/_editors/editors/_zap/!Zap/Docs/E-Zapcalls

Text File | 1994-10-12 | 46KB | 1,082 lines

*************************************************************************
* >E-ZapCalls    Documentation of Zap entry points (how to call Zap)    *
*************************************************************************

Zap does NOT have a SWI interface as it uses registers R8-R10 to point to
data blocks, and these cannot be passed to swi's. To call Zap you will need
to know the address of the Zap module workspace (ie it's private word). If
you are an extension mode then this will be passed to you in R12 whenever you
are called by one of your entry points. However, for the first call you make
to Zap, when you add your module to it's list via Zap_Addmode, you will not
know it. Then you should use OS_Module 18 to find it. Eg,

 SYS "XOS_Module",18,"Zap" TO R0,R1,R2,R3,workspace%

Now, the first word in Zap's workspace contains the address of a table of
Zap's entry points. Thus to call the entry point (documented below) at offset
a% I suggest you use the basic macro given below.

    REM Call Zap at entry offset a%
    REM Entry: R0-R11=args R12=zap workspace
    REM Exit : R0-R11=returned values R12 preserved R14 corrupted

    DEF FNcall(a%)
    [OPTpass
    LDR R14,[R12]        \ get start of zap table
    ADD R14,R14,#a%        \ address of the sub
    STMFD R13!,{R14}        \ save address on stack
    MOV R14,PC            \ return address (with flags)
    LDMFD R13!,{PC}        \ call the sub
    ]:=""

The names of the routines are listed below in the order in which they appear
in the table. Thus the first, Zap_AddMode, is at offset 0. The second,
Zap_Claim is at offset 4, etc. These values are defined for you in the
program E-Library.

In general these routines have the following entry/exit conditions:

 \E R0-R11=arguments R12=Zap's workspace R13=user stack R14=return address
 \X R1-R13 preserved. R0 and Flags ALTERED. V set if error and R0=error block

Thus if I write:

 \E R8
 \X R1=3

Then I mean that on entry R8 was the window block pointer, R12 zap's
workspace etc. And on exit that R1=3, R2-R13 saved, R0 corrupted etc. If I
omit the \E or \X then I mean the standard entry/exit conditions hold.

Errors should be passed back to Zap by the entry point through which the
module was called (with V flag set and R0=error block pointer). Please note
that for most calls, Zap must be paged in as the current task! This will be
so if you are an extension mode.

For a table/summary of the zap call names for including in your source, see
the file E-Library.

Zap_AddMode
Adds a new Zap extension mode. This should be called after the module Zap is
loaded, but before it starts up as a new task. Zap need not be paged in for
this call.
    \E R0=address of table of entry points (see file E-Entry)

Zap_Claim
Claims a block of workspace in Zap's heap.
    \E R0=number of bytes required
    \X R0=pointer to the heap block

Zap_Ensure
Ensures a zap heap block is of a given size.
    \E R0=pointer to the heap block
       R1=number of bytes required.
    \X R0=new heap block pointer of (possibly moved) extended block.
       (An error is returned if the block couldn't be enlarged).

Zap_Free
Free a zap heap block after use.
    \E R0=pointer to heap block to free

Zap_MoveBytes
Moves a block of memory. The movement may be up or down by any amount. The
data is ALWAYS preserved no matter where the destination is. This routine is
highly optimised and should be used for moving any large block of data. Zap
need not be paged in.
    \E R1=source byte address
       R2=destination byte address
       R3=number of bytes to move
    \X R1-R3 corrupted

Zap_SplitBuffer
This splits a file held in Zap at the indicated file offset ready for
insertion/deletion of data. It also ensures that file buffer has a given
amount of room free. See E-File.
    \E R0=file offset to split at (new value for f_splito)
       R1=minimum number of bytes to have free in the split
       R9=file to be split

Zap_NewTxtStatus
This updates the screen after changes are made to a file. This is very low
level and you should use Zap_Command when possible. Zap_SaveTxtStatus should
be called first.
    \E R0/R1 as for SaveTxtStatus and R2=new input caret offset.

Zap_SaveTxtStatus
This is a low level call used by Zap_DoCommand when changing a file. You
should use Zap_Command/Zap_DoCommand in preference. Any file changes done
using this call are NOT saved in the undo buffer. Ie, don't use it. To use it
you specify the area of the file to be changed (R0 to R2) and the amount of
the change (in R1). After making the change you use Zap_NewTxtStatus to
update the screen. Set f_docom to 0 if in doubt.
    \E R0=file offset of first byte in file to be changed.
       R1=proposed signed change in size of file.
       R2=file offset of first character which is unchanged.
       f_docom,f_dolen,f_dodata must be set up - see e_prevline.

Zap_Command
This should be used for inserting/deleting/replacing data in a file. Its
action is to call the mode entry point named e_command. See E-Entry. The
mode's default action is then to call Zap_DoCommand. The commands are
automatically placed in the undo buffer. If you are doing a sequence of
insertions/deletions then please use Zap_Start/StopOp. Note that the cursor
is automatically updated to the end of the inserted/deleted region. To
prevent this, set b14 of f_flags, but you MUST restore it after the command
returns.
    \E R0=command number: 1=insert 2=delete 3=replace (forward)
        4=replace (backward). Add &10 if command is to be buffered
        in one block (and thus undone in one key press).
       R1=file offset for command to take place at.
       R2=number of bytes being inserted/deleted/replaced.
       R3=data to insert/replace with for commands 1,3,4.
       R8=window on file to be altered/0 if none.
       R9=file to be altered.
    NB If you don't specify the window then it won't know which mode to
    call, so this command will just call Zap_DoCommand.

Zap_NewWinStatus
This recreates a window after some display parameters have changed. Use
Zap_SaveWinStatus before changing any parameters.
    \E R8/R9

Zap_SaveWinStatus
This is used before changing any of the 'w_*' window parameters which would
effect the display. See E-Window. The current cursor position, scroll offsets
etc are saved. After changing the window parameters call Zap_NewWinStatus.
Zap will do it's best to recreate the window with the new attributes,
preserving the position of the cursor on screen.
    \E R8/R9

Zap_ReplaceArea
This command replaces one area of text with another (not necessarily of the
same length) by performing the minimum number of insertions/deletions/simple
replaces using Zap_Command. In BASIC mode it also retokenises the line as
necessary. This is used during a search and replace. See mode entry point
e_replace.
    \E R1=file offset of original data
       R2=length of original data
       R3=address of replacement data
       R4=length of replacement data R8/R9

Zap_PlotCaret
This command plots a caret in its new position automatically removing it from
its old position. Ie, it just calls Zap_ClearCaret then Zap_SetCaret.
    \E R10=caret block

Zap_ReflectCaret
This acts as Zap_PlotCaret but only uses c_off, updating the c_loff and c_col
offsets from this. Ie, it just calls Zap_UpdateCaret then Zap_PlotCaret.
    \E R10=caret block

Zap_SetCaret
This updates the area of the window containing the the caret given on entry.
Hence it's effect is usually to draw the caret at it's (new) position. See
E-Cursors.
    \E R10=caret block

Zap_ClearCaret
As for Zap_SetCaret, but it updates the area of the window where the caret
last was (stored in the c_o* variables). Hence the caret is in effect removed
from its old position. See E-Cursors.
    \E R10=caret block

Zap_DoCommand
This acts as Zap_Command but actually performs the action rather than
calling the extension mode.
    \E As for Zap_Command.

Zap_ShowCursor
This call makes sure that a given cursor can be seen in its window (by
changing the scroll offsets if necessary). It does not redraw the cursor
in general (though changing the scroll offsets may cause it to be redrawn).
    \E R10=cursor block of cursor to show

Zap_ReadVar
Reads one of Zaps internal variables. See the file E-Vars for the numbers.
    \E R1=variable number.
    \X R0=variable value.

Zap_WriteVar
Writes one of zaps internal variables. See the file E-Vars for the numbers.
    \E R1=variable number
       R0=new value

Zap_SaveFile
This saves a file to disc (using f_name as the file name). The file may not
actually be saved if a dialogue box is opened. (Eg: 'file is older than
version on disc box'). Please note the value of R0 on exit!
    \E R8/R9 = window to save
    \X R0=0  => File has been saved to disc - you can now delete it.
       R0=-1 => File has not yet been saved - warning window opened /
               data transfer initiated.

Zap_FillWords
Fast word filling code. The block must be word aligned. Zap need not be paged
in.
    \E R1=word to fill with.
       R2=address of memory to fill (word aligned).
       R3=number of bytes to fill (a multiple of 4).
    \X R0-R3 corrupted.

Zap_UpdateLns
This updates the line numbers column of a given window. This is usually done
automatically by Zap_Command. This is used by the BASIC mode on a renumber.
    \E R0=first physical line to start from R8/R9

Zap_EachWindow
This sub calls a given sub for each window on a given file. Each time it
calls the sub pointed to in R10, it sets up R8 for that window.
    \E R0-R7=args to pass to the sub.
       R9=file (whose windows you are to call).
       R10=address of sub to call for each window on this file.
    The sub called has:
        \E R0-R7 as set up by you
           R8/R9 points to the given window
        \X Must preserve R1-R11 and VS on error etc.

Zap_UpdateCaret
This sub is called to update a caret position from a given file offset. Save
the new offset of the caret in c_off. Call this. Then c_col, c_line, c_loff,
c_width will be set up. See E-Cursors.
    \E R10=caret block

Zap_GetWindState
Updates the window block R8 (first few entries) by calling
Wimp_GetWindowState.
    \E R8

Zap_StartOp
Starts a sequence of operations. This should be used when performing a
sequence of calls to Zap_Command. It causes all the file changes to be made
with only ONE screen refresh, thus giving a much smoother update. After this
has been called, all subsequent calls to Zap_Command before a Zap_StopOp call
have their actions concatenated. When you call Zap_StopOp the screen is then
updated. You MUST call Zap_StopOp before returning to Wimp_Poll. StartOp/
StopOp's can be nested to any depth (so only the last StopOp actually causes
the screen to be updated).
    \E R9=file which will be operated on.

Zap_StopOp
Ends a StartOp/StopOp structure.
    \E R9=file which has been operated on.
    \X If VC on entry then R0 corrupted and R1-R11 preserved as usual.
       If VS on entry then error pointer in R0 and V flag status are
       also preserved.

Zap_CallMode
Calls a mode entry point. See E-Entry for a list of entry points. The mode
called is the mode of the window given in R8.
    \E R0-R10=parameters R8 R11=mode entry point offset
    \X As for the given mode entry point.

Zap_CallGivenMode
Calls a mode entry point of a specified mode.
    \E R0-R9=parameters R10=mode number R11=entry point offset
    \X As for the given mode entry point.

Zap_ReadMode
Read the address of the mode entry point tables. Two pointers are returned.
The first (R0) is a pointer to the mode table as stored in the extension
module and documented in E-Entry. The second (R1) points to a table of actual
addresses to be called, with entry points which were null in the original
table converted to addresses and all offsets converted to addresses. In this
table, each entry consists of 8 bytes. The first 4 bytes gives the address of
the entry point, and the next 4 the value to pass in R11 when the entry point
is called. This will obviously vary if some mode entry points are based on
other modes. Thus the linked table has the form:
    e_module    #0    module address,    module workspace address
    e_title        #8    title address,    undefined
    e_author    #16    author address,    undefined
    e_basemode    #24    basemode,    undefined
    e_mode        #32    mode number,    undefined
    e_init        #40    init code addr,    value to pass in R11
    e_menu        #48    wimp menu data,    undefined
    e_len        #56    undefined,    undefined
    e_postload    #64    postload addr,    value to pass in R11
     and the rest as for e_postload.
I reserved the right to use the undefined words in future. You can change the
table entries pointer to in R1, but I don't advise it :-)
    \E R0=mode number.
    \X R0=pointer to unlinked table in modes module / <=0 if invalid
       R1=pointer to linked table in zaps workspace / <=0 if invalid

Zap_FindFile
Given the name of a file, this call produces a window on that file (loading
it if necessary). Path is canonicalised before comparing with currently
loaded files.
    \E R0=file name.
    \X R8/R9=window on that file.

Zap_FindWindow
Given a file block pointer of a file already loaded, this call produces a
window block pointer of a window on that file (opening it if necessary).
    \E R9
    \X R8

Zap_ConvWindOff
Converts a window offset to a window block pointer. See E-Windows.
    \E R0=offset of a window in the window list /-ve
    \X R8/R9=window and file /0

Zap_ConvFileOff
Converts a file offset to a file block pointer. See E-File.
    \E R0=offset of a file in the file list/-ve
    \X R9=pointers to the file block/0

Zap_GetWindOff
Converts a window block pointer to a window offset. See E-Windows.
    \E R8=window block pointer/0
    \X R0=offset in the window list/-ve

Zap_GetFileOff
Converts a file block pointer to a file offset. See E-File.
    \E R9=file block pointer/0
    \X R0=offset in the file list/-ve

Zap_GotoOffset
This call causes the given cursor to jump to a given file offset, leaving a
mark behind at the previous position.
    \E R0=offset to go to R8-R9=file R10=cursor

Zap_JumptoOffset
As for GotoOffset but no mark left on jumping.
    \E R0=offset to go to R8-R9=file R10=cursor

Zap_FindOffset
Given the (x,y) position in work area characters, finds the file offset of
the 'nearest' point in the file. See E-Windows.
    \E R2=x column (inc margin) R3=y row (from top)
    \X R0=file offset R1=file offset of physical line start R2/R3 clipped

Zap_NewFileTitle
Update the titlebars of all windows on a given file.
    \E R9=file

Zap_InsertString
Inserts a string at the end of a buffer using Zap_Command.
    \E R0=zero terminated string R8/R9

Zap_CreateFile
Creates an empty file, possibly changing the opt_flags/format via BIC 'mask'
EOR 'eor' when creating it. See E-Flags, E-Windows. It calls
Zap_CreateWindBlock and Zap_CreateFileBlock etc.
    \E R0=file type
       R1=flags mask
       R2=flags eor
       R3=format mask
       R4=format eor
    \X R8/R9=newly created file (with open window).

Zap_NewLinkEntry
Adds a new link entry to the f_links list. See E-File for description of the
links list format. This is a low-level call. Use Zap_Throwback in preference.
This is used by throwback. A new block is created if the file name does not
match that of the previous link block, or the flags differ. The point of the
links is that they are updated when changes are made to the indicated file.
    \E R0=data word (Ie file offset of link / line number of link
          depending on flags in R5).
       R1=filename (Of the file that R0 is an offset in).
       R4=file offset/-1 (Ie, offset in file list of the file named in
           R1 if the file is loaded, or -1 if you don't know if the file
           is loaded or not - usually safest to put as -1).
       R5=flags (as documented under f_links in E-File).
       R9=file to which the link should be added - ie this is the
          throwback buffer file as opposed to R1 which is the file giving
          the C program / file which was searched through.
    \X R0=0 if link added to last list entry/1 if new entry created.

Zap_DefaultClick
Calls the default mouse click handling code. See the entry point e_click.
    \E R1=depth (0=drag 1=click 2=double click etc)
       R2=x R3=y
       R4=buttons
       R8/R9 as for e_click.

Zap_PutCaret
Sets standard cursor editing mode and puts the cursor caret at a given file
offset in a given file.
    \E R0=file offset R8/R9=file

Zap_DiscardFile
Kill a file and all windows on that file without prompting user.
    \E R9=file

Zap_DeleteFile
As for Zap_DiscardFile but prompts user if file altered etc.
    \E R9=file

Zap_DiscardWindow
Kill a window, and the file if auto-delete is on and this is the last window
on that file. Don't prompt user.
    \E R8/R9

Zap_DeleteWindow
As for Zap_DiscardWindow but prompts user if file altered etc.
    \E R8/R9

Zap_BuildMenu
This is zaps 'variable length menu' building sub. See E-Menu for details on
Zap's menu format.
    \E R0=menu name (max 12 chars)
       R1=address of sub to generate the menu entries
       R2=address of menu updating sub/0 if none (see E-Menu)
       R3=address of menu interpret sub for all entries/0 (see E-Menu)
       R4=menu width in chars
       R8-R11=values to call the sub in R1 with on the first call.
    \X R0=pointer to wimp menu structure
    The sub passed in R1 has the following conditions:
         \E R0=buffer for you to put the next menu entry in (48 bytes)
        R5=address of menu structure start }
        R6=address of current menu entry   } you don't need these
        R7=address of current buf entry    }
        R8-R11=as returned from last call
         \X R0=index for this entry/-1 if no more entries (see E-Menu)
             R1-R7 saved
             R8-R11=updated (ie for your own use).

Zap_ClearSel
Clears currently selected area.

Zap_CreateFileBlock
Creates a new file block with currently configured options. f_ptr etc are set
up for you. See E-File. Use Zap_Install file to load a file.
    \E R0=size to make buffer
       R1=filename of buffer
       R2/R3=load/exec
    \X R9=new file block (with file filled with rubbish).

Zap_CreateWindBlk
Creates a new window block with currently configured options. Window is
opened on the screen etc.
    \E R9=file window is to be on.
    \X R8=New window on this file.

Zap_GetSel
Find out what area is selected.
    \X If CS then no valid selection
       If CC then R1=file offset R2=selection length R8/R9=file

Zap_InsertMark
Insert a marker.
    \E R0=file offset of mark R8/R9

Zap_InstallFile
Load a file into zap.
    \E R0=filename
    \X R0=window offset of created window / -1 if not loaded.

Zap_NewMode
Change the display mode of a window.
    \E R0=new mode number R8/R9 (R8=0 to change options mode)

Zap_NewTitle
Update the titlebar on a given window. See also Zap_NewFileTitle.
    \E R8/R9

Zap_CallBaseMode
DO NOT USE THIS. This call is now obsolete. Use the call Zap_BaseMode
instead. If you use this call it will appear to work perfectly until someone
tries to use your mode as a base mode. When this happens an infinite loop
occurs which I can't fix. The docs are kept for backwards compatibility.
--------------------------------------------------------------------------
As for Zap_CallMode except it calls the base mode instead. The window in R8
identifies the current mode. The entry point called is that of the base mode
associated to this current mode. Hence, it would be used by a mode to call
a base mode entry point which the current mode has redefined.
    \E R0-R10=parameters R8 R11=mode entry point offset (see E-Entry)
    \X As for the given mode entry point.

Zap_NewView
As for Zap_CreateWindBlk but 'clones' a given window image. The cursor is not
put in the window.
    \E R8/R9=window to clone from (R8=0 then don't clone)

Zap_ReadSel
Reads the currently selected region into a heap block. You must free the heap
block when you have finished with the selection.
    \X R3=heap block with data and R2=length / R3=0 if no selection

Zap_Replace
Calls the Zap file search and replace code using the current search string
and current replace string.
    \E R1=0 for selective/1 for global
       R3=start offset in file
       R4=direction (+1/-1)
       R5=search flags (as for Zap_Search)
       R8/R9=current window

Zap_Search
Calls the Zap wildcard search code.
 \E R0=pointer to search string
    R1=output 0=to cursor 1=to buffer 2=no output
       OR &100+offset of throwback window to add search matches to.
    R3=start offset of the search (in the file)
    R4=search direction +1/-1
    R5=search flags b31=set for a raw search (don't search by lines)
            b30=set if case sensitive
            b29=set if macros shouldn't be expanded
            b28=set if \commands should be ignored (and `s etc)
            b27=set to search all windows (move to next one after)
            b26=don't update hourglass in search_text
            b25=don't beep if no match found
            b24=return end of match offset in R1 (if one found)
    R8/R9=current window of search
 \X If R1=0 or 1 then output displayed
    If R1=0 or 2 then R0=match offset on exit / -ve if none
    If R1=1 then R0=offset of throwback window / -ve if none
    R1=offset of end of match (if b24 of R5)

Zap_Select
Selects a given region, and puts carets back to default mode.
    \E R2=start offset R3=end offset R8/R9

Zap_AlterSel
As for Zap_Select but doesn't restore caret modes.
    \E R2=start offset R3=end offset R8/R9

Zap_OffLineCol
Converts a file offset to and x,y coordinate in the window work area. See
also Zap_FindOffset. See E-Windows.
    \E R0=file offset R8/R9
    \X R0=start of line offset
       R2=column (inc margin)
       R3=row

Zap_AddCommands
Adds a table of commands to zap's list. Zap can currently cope with up to 16
tables of commands. This should be called when a module initialises as for
Zap_AddMode. Zap need not be mapped into memory for this call. See E-Commands
for the table format.
    \E R0=address of command table (R12=Zaps workspace).

Zap_MiniWrite
This call sends a stream of characters to the minibuffer. The minibuffer
contents is changed but not updated on screen. However, if this call is used
within a command, then the minibuffer will updated on screen automatically
by Zap. Use Zap_MiniUpdate to force an update, but you shouldn't have to use
this. The minibuffer takes the form:
    <prompt string><mark><user editable field>.
The user cannot move the cursor before the 'invisible' mark. The string
passed to Zap_MiniWrite may contain the following control codes:
    0=string terminator
    1=move cursor to mark (ctrl a)
    2=8=move cursor back one character (ctrl b)
    4=delete character after cursor (ctrl d)
    5=move to end of string (ctrl e)
    6=9=move cursor forward one character (ctrl f)
    11=clear buffer from cursor (ctrl k)
    12=clear whole buffer (ctrl l)
    21=clear buffer from mark (ctrl u)
    28=set mark to current cursor offset
    127=delete character before cursor
When a command with string parameter is called, R0 points to the user
editable part of the string.
    \E R0=pointer to zero terminated string

Zap_MiniPrompt
This replaces the prompt string in the minibuffer with the given string. It's
main use is for reason code R2=6 when a command with string parameter is
called (see E-Commands). The buffer is not updated on screen (see
Zap_MiniWrite). Unlike Zap_MiniWrite, the minibuffer cursor is not affected
by this call (It remains the same number of characters after the mark).
    \E R0=new prompt string

Zap_MiniUpdate
This call updates the minibuffer on screen (if open). This will usually be
done automatically by Zap.

Zap_AddYankRegion
This call adds a region to the cut/paste kill ring. The region you pass it
is not copied so must be stable (eg in a heap block).
    \E R0=address of region + flags:
        b31 MUST BE SET (If clear then denotes an undo buffer ref).
        b30 If set, then after yanking this block, it will move onto
            the block before (ie, yanks many blocks at once).
       R1=block length (provided b31 of R0 is set).

Zap_FindCommand
This call converts a command name into a command address by looking it up in Zaps command tables.
    \E R0=command name terminated by <=32 or :,&,"
    \X R0=command address / 0 if not found

Zap_ProcessCommand (see also Zap_CommandString).
 This makes a call to a Zap command. It should be used for all calls to
commands. You can find the address of a command via Zap_FindCommand. You
may also call commands which may not have a name - it just considers the
command address.
 The data the command takes is pointed to in R0. The data format depends on
the command. It should point to a list of bytes/word or a string depending on
whether the command takes a byte/word or string parameter. It is undefined if
the command takes no parameter. See E-Commands for more details. Put R0=0
instead of the pointer to a string to open the minibuffer instead.
 The number of times the key has 'auto-repeated' is passed in R1. This will
be the length of the byte/word list if the command takes byte or word
parameters. Usually put R1=1.
 R2 holds the action code of the command. Action code 0 executes the command.
The other action codes are used to read information about the command and are
mainly used internally by Zap. See E-Commands for the details.
 NB The mode e_aligncaret entry point will be called before all command calls
using R2=0,1 on entry.
 \E R0=pointer to command data (0 if there is no data)
       R1=length of the command data if byte or word list (in bytes or
          words). Number of times key has auto-repeated otherwise.
       R2=Command action code:
           b0-b27 = Action code to be passed to the command. 0 to
                execute it - see E-Command.
           b28-b31= Flags to tell Zap_ProcessCommand things. These are
                filtered out before R2 is passed to the command.
                b31=Set if command should not be learnt even
                    if in learn mode.
             b30-b28 reserved.
       R7=command address (need not point to a command registered in a
               command table, but must conform to the specs in the
               file E-Command. Eg, [R7,#-4] must be the flags word).
       R8=window block pointer or 0 if none applicable (options menu)
       R9=file block pointer or 0 if none applicable (options menu)
       R10=input cursor (or cursor you wish command to act on) or 0
           if not applicable.
 \X R1-R13 preserved.
    If action code=0 on entry then R0=0 or -1 if minibuffer opened.
    If action code>0 on entry then R0=value in R0 when command returned.

Zap_FindKeyEntry
This finds the entry corresponding to a given key and keymap. You might use
it for redefining the key for instance. The block pointed to on exit has the
format:
    #0 Command address (or 0 if none - key is passed on to wimp)
    #4 Command parameter, this depends on the command flags b3-7. If
       these bits are:
       0   => #4 undefined (should be 0)
       1/2 => #4 is the byte or word to be added to the list to be
             passed to the command when the key is pressed.
       3   => #4=address of string parameter /0 if minibuffer should be
              used.
       4   => #4=address of the data block.
    \E R0=keymap number R1=zaps key number (0-&1FF)
    \X R0=entry for this key / 0 if keymap does not exist or key is
       out of range.

Zap_FindLeafName
This works out which part of a filename is the leafname.
    \E R0=filename pointer
    \X R0=pointer to the leafname part (within the filename).

Zap_NewFileName
Change the name of a given file. You may have to call Zap_NewFileTitle to
update the titlebars (this will usually be done by Zap_SaveFile).
    \E R0=new file name R9

Zap_CheckFileName
Decides whether a filename is a full path name (eg "ADFS::$.Wibble") or just
the leaf name of a file (eg "Text1"). Should be used in conjunction with
Zap_SaveFile as this will not save files without full path names.
    \E R0=filename
    \X R0=0 if it is a full path name / 1 otherwise

Zap_GetCurrDir
Returns current directory (of the temporary filing system) which should be
used as default string in minibuffer file operations. On RISC OS 2, there is
no way of reading the current directory so this call returns the root
directory on the current disc (via OS_Args 0, OS_FSControl 33, OS_GBPB 5). On
RISC OS 3, the current directory is read via OS_Args 0, OS_FSControl 33, and
OS_FSControl 54. NB The block it is returned in is not stable over calls to
Zap. You may call Zap_MiniWrite passing this block but should copy the
string for other calls.
    \X R0=pointer to 256 byte buffer containing the directory name

Zap_MiniWriteC
Writes a single character to the minibuffer. See Zap_MiniWrite for the
character codes.
    \E R0=character to insert in minibuffer.

Zap_MiniClear
Clears minibuffer contents without updating on screen. Resets marks etc. You
should use this before using Zap_MiniStart.

Zap_MiniStart
This starts up the minibuffer. Do not use this call when writing a Zap
command. Read the file E-Command to see how the minibuffer works in this
case. You never need this call, Zap_ProcessCommand can open a minibuffer at
any time if you feed it a string type command and R0=R2=0.
    \E R7=address of command to be called when return pressed in
       minibuffer. [R7,#-4] must contain the command flags word as
       documented in E-Command.
       R8/R9=window minibuffer should appear at.

Zap_MiniEval
This turns a string into a number via OS_EvaluateExpression. It is usually
called near the start of a command which expects to find a number in the
minibuffer.
    \E R0=string pointer (usually minibuffer pointer passed to you)
    \X R0=number stored in string/CS if not a valid number.

Zap_CommandString (see also Zap_ProcessCommand)
This call takes a command (or colon separated list of commands) in string
form and executes them as typed. For example if R0="MODE 0" on entry then
first of all a call to Zap_FindCommand will be made to find the address of
the command "MODE" and then the command will be called via
Zap_ProcessCommand with R2=0.
    \E R0=command string (zero terminated)
          Set b31 if you don't want the commands to be learnt if in
          learn mode.
    \X R0=0 or -1 if the minibuffer has been opened.

Zap_ProcessKeys
This entry point accesses Zap's main key handling sub so you can simulate
keypresses. If you just wish to simulate one key press, then it is easier to
use the next call. This call is for multiple keypresses and buffers the data
as much as possible before it has to call a command. You must keep calling
this command until it returns R0<0 (as it will do if you put R5=-1 on entry -
it uses the R5=-1 call to execute the buffered data).
    \E R0=zap key number of next key to execute (if R5>=0)
       R5=-1     => there are no more keys to buffer (R0 not defined).
          0-&1FF => wimp key number of key to send to Wimp_ProcessKey
               if no command is attached to the key.
          &200   =>    if Wimp_ProcessKey should never be called.
       R6=length of current buffering (set to 0 on first call)
       R7=command currently being buffered (if R6>0)
       R8-R10=input cursor
    \X R0>=0 if you should call this sub again with the next key (or
          R5=-1 if there are no more).
       R0<0 if the command has finished processing all buffered data
          so you needn't call it again.
       R6/R7 are updated for the next call.

Zap_ProcessAKey
This command simulates a key press by calling the above command twice, once
with the key and then once with R5=-1.
    \E R0=zap key number
       R5=wimp key number (see Zap_ProcessKeys)
       R8-R10=input caret

Zap_OpenWindow
The current position of a Zap window can be read easily using the code:
 MOV R1,R8 : SWI "XWimp_GetWindowState". However, you should not call
Wimp_OpenWindow to open a window as Zap has to keep track of the title length
and position of the minibuffer etc. You should use this call instead. Use
call 0 where possible as it prevents titlebar flicker.
    \E R0=type of open:
        0 => Just changing scroll offsets or height in window stack.
             Size/position of window NOT changing.
        1 => Window may move/change size. Minibuffer, title bar
             and cursors dealt with accordingly.
        2 => Window is a new window. Toggle size data etc reset.
        3 => Bring window to front of stack (ignore R1)
        4 => Put window to back of stack (ignore R1)
        5 => As for 0, but cursor kept within the window if the
             'constrict cursor' option is on.
        (NB type 2 calls type 1 calls type 5 calls type 0)
       R1=open block (as for Wimp_OpenWindow)
       R8=window block (NB Usually alter this block and let R1=R8)

Zap_RestoreModeWord
This call should be used by your e_start entry point. If R8<>0 on entry then
it reads the reads the options for the given mode from w_datablock using the
call Zap_ModeData, and sets them as the current options. If R8=0 then it does
the same thing but sets the default options.
    \E R0=mode number
       R8=window to restore options on / 0 for the default options.

Zap_SaveModeWord
This call should be used by your e_end entry point. If R8<>0 on entry then it
reads the words w_flags and w_format and stores the current options in the
w_modedata block by use of the call Zap_ModeData. If R8=0 on entry then it
reads opt_flags and opt_format and stores them as the default option etc.
    \E R0=mode number
       R8=window to save options on / 0 for the default options.

Zap_GetModeWord
This call reads the contents of your mode word. If R8=0 then it reads
opt_moden, otherwise it reads [R8,#w_moden]. This is useful for menu
options.
    \E R1=mode number
       R8=window to get mode word / 0 for default options mode word
    \X R0=mode word contents.

Zap_PutModeWord
As above, but write the value.
    \E R0=new value for the word
       R1=mode number
           R8=window to put mode word / 0 for default options mode word

Zap_BaseMode
This call replaces Zap_CallBaseMode. It differs in that you must specify
which mode is calling. This information is not necessarily available from
the block in R8 if another mode is based on yours. The basemode of the mode
named in R9 is called via the entry point offset given in R11. Before the
entry point is actually called, R9 is converted to the file block pointer
of the window specified in R8. Hence any entry point requiring R8 and R9
set up on entry can be called ok.
    \E R0-R7=parameters for the call
       R8=window block to be used by the call.
       R9=mode number making this call (your mode number).
       R10=parameter for the call (usually cursor block pointer).
       R11=mode entry point offset (see E-Entry) to call.
    \X As for the given mode entry point.

Zap_ReadWord
This call can be used for reading 4 byte from a file buffer. Note that
although the offset of the word in the file may be word aligned, it's offset
in the buffer may not be due to the split. This call reverses the word if the
Big Endian flag is set.
    \E R0=File offset of the word to be read
       R8=window (for big endian flag to be read)
       R9=file
    \X R0=the word read (padded with zeros if it went off the file end).

Zap_ReplaceWord
This call replaces a word at the given file offset (inserting if the file
offset+4>file length) via Zap_Command. The word is reversed if the big endian
flag is set.
    \E R0=word to replace
       R1=file offset
       R8/R9 (R8 used for the big endian flag).

Zap_ModeColour
This call reads or writes the colour definition table. It will not usually
have immediate effect unless you recreate the window (eg Zap_NewWinStatus).
You shouldn't usually access this data as Zap handles it all for you, except
to write sensible default values (using R8=0) if your mode starts up and
finds its mode word is zero.
    \E R0=colour to write:
          -1   => Don't write anything (just read the value)
          b0-b7 <16 => Write this wimp colour (converting it to RGB)
          b0-b7 >15 => Write 24 bit colour of the form &BBGGRRZZ
               where ZZ is the Zap style (&10=base style)
       R1=mode number
       R2=Zap colour number of the colour to write/read:
          0/1=Background 2=Foreground 3=Selection background
          4=selection foreground 5=cursor back 6=cursor for
          7=line numbers 8=control chars
          9+ mode dependent extension colours.
       R8=Window block to read from / 0 for default (!Config) settings.
    \X R0=colour value read / old value if writing it. This is of the
          form &BBGGRRZZ as above.

Zap_FindInput
This call works out the current position of the 'input focus' in a window. If
the input caret is in this window then it returns it's offset. Otherwise it
returns the 'point' position (usually marked by an empty square).
    \E R8/R9
    \X R0=most suitable offset to insert data.

Zap_ClipCache
This call moves the cache reference point (w_cline/coff/clogl etc) to a given
point (using e_clnoff).
    \E R0=Offset in line to move the cache reference point to. R8/R9

Zap_ModeData
This call reads or write the mode dependant options that Zap handles
automatically for you. See also Zap_ModeColour. Currently there is only one
word per mode storing the width and things like whether auto-indent is on or
not. You should use this call with R8=0 to write sensible default values if
your mode starts up and finds its mode word is zero. If you don't then the
default Text mode values will be used.
    \E R0=value to write / -1 to read
       R1=mode number
       R2=variable number to read write
       R8=window concerned / 0 for the default (!Config) settings.
    \X R0=variable value if read / old value if written
    Variables num:    0     b0-b15  stores the "width" for this mode
                b16    auto indent bit (b16 of w_format)
                b17     auto width bit (b6 of w_flags)
                b18    strip spaces bit (b18 of w_format)
                b19-b21 tab mode bits (b9-b11 of w_flags)
                    b19-b20 0=Unix 1=Edit 2=Coltab
                    b21=insert tabs as spaces
                b22    hex entry mode bit (b5 of w_flags)
                b23    overwrite bit (b1 of w_flags)
                b24-b31    display bits (b8-b15 of w_format)
                    b24=line numbers shown
                    b25=line numbers as lines (not addr)
                    b26=line numbers in hex
                    b27=logical line nums (not physical)
                    b28-29 0=no tabs 1=spaces 2=> 3=->
                    b30=line edit paradigm
                    b31=non standard editing
            1+    reserved.

Zap_WhichMode
This call decides which mode a given file should be displayed in.
    \E R0=load address of file (containing the filetype)
       R1=filename pointer / 0 if not known
    \X R0=flags    b0 => Auto load flag is set, no shift test.
       R10=mode file should be loaded into.

Zap_ModeNumber
This calls turns a mode name (given by a string) into a mode number.
    \E R0=mode name string terminated by <= space (&20)
    \X R0=mode number or -1 if not found.

Zap_SendDataSave
This call initiates the save protocol, saving data to another window or
application via RAM transfer or WimpScrap. It sends the data_save message and
all replies are handled automatically.
    \E R2=proposed file/leaf name of the data (or 0 to use the file's)
       R3=destination window handle or task handle
       R4=destination icon handle (if R3=-2)
       R5/R6=destination mouse coords (if applicable)
       R7=routine to call after save finished (or 0 if none).
       R8/R9=R8<>0 => Save whole file R8=window block R9=file block
            R8=0  => Save currently selected region.
            (or set b1 of R10 to save an arbitrary region).
       R10=b0-b15 flags:
           b0 set => External edit flag. In this case R3=ext edit
                job handle and R4=ext edit task handle and
                external edit message sent instead.
           b1 set => R8=start address of data to save
                    R9=size of the data to save
                    b12-b31 of R10=filetype of data to save.
           b16-b31 = extra data (see b1)
       R11=data to pass to routine in R7 (if used).
    \X Data transfer protocol initiated.
    Sub pointed to by R7 is called with R11 as passed above and should
    preserve R1+ as usual.

Zap_Warning
Warns the user without generating an error. This opens a window with the
given message and pauses for the message to be seen before returning. Wimp
Poll is not called.
    \E R0=warning message
       R1=time to leave message open in cs (0 for default delay)
          + flags:
           b31 => Don't beep when opening the window
       R8/R9=window in which to show the warning.

Zap_AllWindow
Calls a given subroutine once for each valid Zap window. See also
Zap_EachWindow.
    \E R0-R7=arguments to pass to the sub
       R10=address of the sub to call (which must preserve all registers
           except R0, and is called once for each window with R8/R9
           set up to be that window).

Zap_ReadMenu
Converts a text file of the same format of Zap's 'Menu' file into a Zap menu
structure.
    \E R0=start of a zero terminated menu text file (stored in memory)
    \X R0=pointer to heap block containing the following information
        #0 Number of valid menu handles for this file (first
           number appearing in the file)
        #4 Pointer to the menu structure (in Zap-Wimp format) for
           handle 0 (or 0 if handle 0 not used)
        #8 Pointer to structure for handle 1
        #12 Pointer to structure for handle 2 etc.

Zap_LoadMenu
Converts a text menu file to a Zap menu structure.
    \E R0=pointer to filename of the menu file
    \X R0=list of menu handles as for Zap_ReadMenu

Zap_OpenMenu
Opens a menu on the screen. The menu structure is handled automatically once
it has been opened.
    \E R1=pointer to Zap-Wimp menu structure
       R2=mouse x to open at
       R3=mouse y to open at
       R8/R9=window the menu is being opened on or 0's for none (eg the
         iconbar menu).

Zap_CallBack
Schedules a subroutine to be called again at a certain time but using wimp
null events.
    \E R1=(earliest) monotonic time to call back at (>0)
          or -(smallest delay before calling back) =< 0.
       R2=address of routine to call.
       R3=data to pass to the routine in R11.
    The routine pointed to by R2 has conditions:
     \E R1=current time R11=value passed in R3
     \X (must save R1+ as usual)

Zap_DragBox
Starts a wimp drag box making sure you get called when it's finished.
    \E R0=b0 set if you wish to be called repeatedly during the drag
          b1+ reserved (set to 0)
       R1=drag box block to be passed to Wimp_DragBox
       R2=address of routine to call.
       R3=data to pass to the routine in R11.
    The routine pointed to by R2 has conditions:
     \E R0=reason code 1=drag in progress 2=drag has just finished
        R1=drag box posn as returned by wimp if R0=2
        R11=value passed in R3
     \X (must save R1+ as usual)

Zap_SendMessage
Sends a wimp message and logs the message number (my_ref) so that any reply
can be forwarded to you. The message reference is held for at least a minute
and only deleted on a null event.
 E R0=b0-b27 message action number (to go in R1,#16)
      b28    set if you are interested in the reply.
      b29    set if you want to be called when message deleted
      b30-31 00 => Just send the message (with code 17)
          01 => Just acknowledge the message (with code 19)
          10 => Send the message recorded (with code 18) and call the
            reply code if the message replied to.
          11 => Send the message recorded (with code 18) and call the
            reply code if the message replied to or bounces.
   R1=message block
   R2=dest task handle/window handle
   R3=b31 clear => This is the message length (is rounded up to next word)
      b31 set   => This is the offset of a string ending the message.
   R4=icon handle if R2=-2 (iconbar) [not used otherwise]
   R5=address of routine to call when message replied to [if b28 of R0]
      (zero as a value means that you want any replies to be dealt with
       as if they were normal messages and not a reply)
   R6=private word to pass to routine on a reply [if b28 of R0]
 X The message is sent as an original message. Hence the my_ref, length
   and message action fields are filled in for you. R0=task handle of the
   dest task (R2 on exit from Wimp_SendMessage)
     Routine in R5 called with:
         ;E R0=message type
             0 => message being removed from log list (see b29)
             17 => message replied to as normal
             19 => message bounced
            R1=message block
            R2=message number (R1!16) R11=private word R12=Zap's etc
         ;X You can corrupt R0-R11 if R0=17,19
            You should save R1-R11 if R0=0

Zap_Reply
Replies to a message. It copies my_ref to your_ref for you can reads the task
handle of the task to reply to from the message block. The length word is
assumed to be unchanged.
 E R0=message action number (as for SendMessge)
   R1=message block (with ref etc)
   R5/R6=rountine to handle the reply if b28 of R0 (as for SendMessage)

Zap_Extend
Changes the size of a heap block, making it smaller or bigger as for OS_Heap
with the extend action code.
 \E R0=pointer to the heap block R1=signed change in the size
 \X R0=new heap block pointer (it may have moved)

Zap_ModeColourNum
Reads/writes the size of the colour palette used by a given mode. Maximum
size of a palette is currently 256 colours. Use R8=0 to read the default
values. NB If you enlarge the palette then please write some sensible values
for the new entries!
 \E R0=new size of palette (in number of colours) / -1 to read
    R1=mode number R8/R9=window or R8=0 for the default options.
 \X R0=old size / read size.

Zap_CreateThrowback
Creates a throwback buffer ready for lines being inserted by Zap_Throwback.
 ;E R0=suggested width of window / 0 to use default width
 ;X R0=window offset of window R8/R9=newly created throwback window

Zap_Throwback
Inserts a line in a throwback file for you.
 \E R0=file offset or line number of line with info on it
       set b31 to supress this being printed automatically.
    R1=filename (of the file that R0 is an offset in)
    R2=information string to print after the line number (eg "Bad syntax")
    R3=string to precede filename  (eg "Errors in file:")
    R4=file offset of linked file / -1 if may not be loaded
    R5=flags to use for the new entry (see f_links,#12)
    R6=string to precede new info block (eg "Line num  Error")
    R7=string to go after filename (eg 10,"Search string: fred")
    R8/R9=throwback window to add entry to
 \X Throwback entry added and new title block given if file (or flags)
    have changed KB #
    The line number field is 10 characters wide if not supressed.